// <copyright file="Gender.cs" company="Alan Dean">
// The MIT License

// Copyright (c) 2008 Alan Dean

// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:

// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.

// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
// THE SOFTWARE.
// </copyright>
// <author>Alan Dean</author>
// <email>alan.dean@thoughtpad.net</email>

namespace Semantic.Rdf.Foaf
{
    using System;
    using System.Diagnostics.CodeAnalysis;
    using System.Runtime.Serialization;

    /// <summary>
    /// Represents a FOAF <see href="http://xmlns.com/foaf/spec/#term_gender">gender</see> property.
    /// <para>This class cannot be inherited.</para>
    /// </summary>
    /// 
    /// <remarks>
    /// <para>The gender of this Agent (typically but not necessarily 'male' or 'female').</para>
    /// <para>
    /// The <see href="http://xmlns.com/foaf/spec/#term_gender">foaf:gender</see> property relates a <see cref="T:Semantic.Rdf.Foaf.Agent">foaf:Agent</see>
    /// (typically a <see cref="T:Semantic.Rdf.Foaf.Person">foaf:Person</see>) to a string representing its gender.
    /// In most cases the value will be the string 'female' or 'male' (in lowercase without surrounding quotes or spaces).
    /// Like all FOAF properties, there is in general no requirement to use foaf:gender in any particular document or description.
    /// Values other than 'male' and 'female' may be used, but are not enumerated here.
    /// The foaf:gender mechanism is not intended to capture the full variety of biological, social and sexual concepts associated with the word 'gender'.
    /// </para>
    /// <para>
    /// Anything that has a foaf:gender property will be some kind of foaf:Agent.
    /// However there are kinds of foaf:Agent to which the concept of gender isn't applicable (eg. a foaf:Group).
    /// FOAF does not currently include a class corresponding directly to "the type of thing that has a gender".
    /// At any point in time, a foaf:Agent has at most one value for foaf:gender.
    /// FOAF does not treat foaf:gender as a static property;
    /// the same individual may have different values for this property at different times.
    /// </para>
    /// <para>
    /// Note that FOAF's notion of gender isn't defined biologically or anatomically
    /// - this would be tricky since we have a broad notion that applies to all foaf:Agents
    /// (including robots - eg. Bender from Futurama is 'male').
    /// As stressed above, FOAF's notion of gender doesn't attempt to encompass the full range of concepts associated with human gender, biology and sexuality.
    /// As such it is a (perhaps awkward) compromise between the clinical and the social/psychological.
    /// In general, a person will be the best authority on their foaf:gender.
    /// Feedback on this design is particularly welcome (via the FOAF mailing list, <see href="http://rdfweb.org/mailman/listinfo/rdfweb-dev">rdfweb-dev</see>).
    /// We have tried to be respectful of diversity without attempting to catalogue or enumerate that diversity.
    /// </para>
    /// <para>
    /// This may also be a good point for a periodic reminder:
    /// as with all FOAF properties, documents that use 'foaf:gender' will on occassion be innacurate, misleading or outright false.
    /// FOAF, like all open means of communication, supports lying.
    /// Application authors using FOAF data should always be cautious in their presentation of unverified information,
    /// but be particularly sensitive to issues and risks surrounding sex and gender (including privacy and personal safety concerns).
    /// Designers of FOAF-based user interfaces should be careful to allow users to omit foaf:gender when describing themselves and others,
    /// and to allow at least for values other than 'male' and 'female' as options.
    /// Users of information conveyed via FOAF (as via information conveyed through mobile phone text messages, email, Internet chat, HTML pages etc.)
    /// should be skeptical of unverified information.
    /// </para>
    /// </remarks>
    /// 
    /// <seealso href="http://xmlns.com/foaf/spec/">
    /// FOAF Vocabulary Specification
    /// </seealso>
    [Serializable]
    public sealed class Gender : Triple
    {
        #region fields

        /// <summary>
        /// Stores the <see cref="P:Semantic.Rdf.Foaf.Gender.Predicate"/> data.
        /// </summary>
        private static readonly IUriReference _predicate = new UriReference("http://xmlns.com/foaf/0.1/gender");
        
        #endregion

        #region public Gender(Agent, object)
        /// <overloads>
        /// Overloaded.
        /// Initializes a new instance of the <see cref="T:Semantic.Rdf.Foaf.Gender"/> class.
        /// </overloads>
        ///
        /// <summary>
        /// Initializes a new instance of the <see cref="T:Semantic.Rdf.Foaf.Gender"/> class
        /// with the specified <paramref name="subject"/> and <paramref name="obj">object</paramref>.
        /// </summary>
        ///
        /// <param name="subject">The subject of the triple.</param>
        /// <param name="obj">The object of the triple.</param>
        /// 
        /// <exception cref="T:System.ArgumentNullException">
        /// <paramref name="subject"/> is a <see langword="null"/> reference.<br/>-or-<br/>
        /// <paramref name="obj"/> is a <see langword="null"/> reference.
        /// </exception>
        [SuppressMessage("Microsoft.Naming", "CA1720:IdentifiersShouldNotContainTypeNames", MessageId = "obj", Justification = "This is the appropriate naming.")]
        public Gender(Agent subject, object obj)
            : base((null == subject) ? null as IUriReference : subject.Subject, _predicate, obj)
        {
        }
        #endregion

        #region public Gender(IUriReference, object)
        /// <summary>
        /// Initializes a new instance of the <see cref="T:Semantic.Rdf.Foaf.Gender"/> class
        /// with the specified <paramref name="subject"/> and <paramref name="obj">object</paramref>.
        /// </summary>
        ///
        /// <param name="subject">The subject of the triple.</param>
        /// <param name="obj">The object of the triple.</param>
        /// 
        /// <exception cref="T:System.ArgumentNullException">
        /// <paramref name="subject"/> is a <see langword="null"/> reference.<br/>-or-<br/>
        /// <paramref name="obj"/> is a <see langword="null"/> reference.
        /// </exception>
        [SuppressMessage("Microsoft.Naming", "CA1720:IdentifiersShouldNotContainTypeNames", MessageId = "obj", Justification = "This is the appropriate naming.")]
        public Gender(IUriReference subject, object obj)
            : base(subject, _predicate, obj)
        {
        }
        #endregion

        #region private Gender(SerializationInfo, StreamingContext)
        /// <summary>
        /// Initializes a new instance of the <see cref="T:Semantic.Rdf.Foaf.Gender"/> class
        /// from the specified instances of the <see cref="T:System.Runtime.Serialization.SerializationInfo"/>
        /// and <see cref="T:System.Runtime.Serialization.StreamingContext"/> classes.
        /// </summary>
        /// 
        /// <param name="info">
        /// An instance of the  <see cref="T:System.Runtime.Serialization.SerializationInfo"/> class
        /// containing the information required to serialize the
        /// new <see cref="T:Semantic.Rdf.BooleanLiteral"/> instance. 
        /// </param>
        /// <param name="context">
        /// An instance of the <see cref="T:System.Runtime.Serialization.StreamingContext"/> class
        /// containing the source of the serialized stream associated with the
        /// new <see cref="T:Semantic.Rdf.BooleanLiteral"/> instance.
        /// </param>
        /// 
        /// <exception cref="T:System.ArgumentNullException">
        /// <paramref name="info"/> is a <see langword="null"/> reference.
        /// </exception>
        private Gender(SerializationInfo info, StreamingContext context)
            : base(info, context)
        {
        }
        #endregion
    }
}